.. index:: simplan .. _simplan: .. _simulation_plans: The properties =============== .. index:: simplan.endo_list .. _simplan.endo_list: endo_list ---------- endo_list - list of endogenous .. index:: simplan.exo_list .. _simplan.exo_list: exo_list --------- exo_list - list of exogenous .. index:: simplan.par_list .. _simplan.par_list: par_list --------- par_list - list of parameters .. index:: simplan.def_list .. _simplan.def_list: def_list --------- def_list - list of definitions .. index:: simplan.start_date .. _simplan.start_date: start_date ----------- start_date - last date of history .. index:: simplan.end_date .. _simplan.end_date: end_date --------- end_date - last date of simulation .. index:: simplan.InitialRegime .. _simplan.InitialRegime: InitialRegime -------------- InitialRegime - Initial regime for forecasting .. index:: simplan.DynamicConstraints .. _simplan.DynamicConstraints: DynamicConstraints ------------------- DynamicConstraints - constraint,shocks,date,page .. index:: simplan.ConditionMatrix .. _simplan.ConditionMatrix: ConditionMatrix ---------------- ConditionMatrix - 3D matrix for simulation conditions .. index:: simplan.partitions .. _simplan.partitions: partitions ----------- simplan/partitions is a property. .. index:: simplan.simul_periods .. _simplan.simul_periods: simul_periods -------------- simplan/simul_periods is a property. .. index:: simplan.variable_list .. _simplan.variable_list: variable_list -------------- simplan/variable_list is a property. The methods ============ .. index:: simplan.append .. _simplan.append: append ------- `append` - Add conditioning restrictions to a simplan object. Syntax:: obj = append(obj, vname, date, value) obj = append(obj, vname, date, value, page) obj = append(obj, {vname, date, value}) obj = append(obj, {vname, date, value, page}) obj = append(obj, C) obj = append(obj, S, date) obj = append(obj, S, date, page) Description: Adds conditioning restrictions to a simplan object. A restriction pins a variable to a target value at one or more dates, optionally at a specific anticipation page (shock horizon lead). Restrictions can target: - A single endogenous or exogenous variable by name. - An algebraic constraint paired with a fixing shock. - Multiple variables at once via a struct or cell array. `append` can be called multiple times. Each call adds to the existing restrictions without removing previous ones. If the same variable-date-page combination is set twice, the later call wins. Inputs:: - obj : Existing simplan object. - vname : Variable name or constraint specification. One of: string Name of an endogenous or exogenous variable, e.g. 'inflation'. Must be in variable_list. 1x2 cell Algebraic constraint paired with a fixing shock: {constraint, fixingShock}, where constraint is a string expression such as 'Inflation{t} + Output = 0' and fixingShock is the name of the shock enforcing it. - date : Date or vector of dates at which the restriction applies. Must be within [start_date, end_date]. Dates must be of the same type as the simplan horizon (numeric or RISE). - value : Target value(s) for the restriction. Must be real numeric. Compatibility with date: scalar + scalar date -> one entry scalar + vector dates -> value replicated across dates vector + vector dates -> paired element-wise; lengths must match vector + scalar date -> error (ambiguous) - page : (Optional) Anticipation lead + 1. Positive integer. page 1 = shock is unanticipated (hits at date) page k = shock is known k-1 periods ahead of date Defaults to 1 (unanticipated) if not provided. Maximum page is determined by the model's shock_horizon. - C : Cell array where each row is one restriction. Accepts: {vname, date, value} 3-column, page defaults to 1 {vname, date, value, page} 4-column Rows can mix variable names and algebraic constraints. - S : Struct with variable names as fields and numeric scalar or vector values. All fields must have the same number of values. Unrecognized fields trigger a warning and are ignored. Combined with a date argument: append(obj, S, date) page defaults to 1 append(obj, S, date, page) explicit page Outputs:: - obj : Updated simplan object with the appended restrictions. Examples:: % Pin inflation to 2% at a single date sp = append(sp, 'inflation', rq(2021,1), 0.02); % Pin output to 1.0 across a range of dates sp = append(sp, 'output', rq(2021,1):rq(2021,4), 1.0); % Anticipated shock: ea is known 2 periods ahead sp = append(sp, 'ea', rq(2022,1), 0.1, 3); % Multiple variables via cell array C = {'inflation', rq(2021,1), 0.02; 'output', rq(2021,1), 1.00}; sp = append(sp, C); % Multiple variables via struct S.inflation = 0.02; S.output = 1.00; sp = append(sp, S, rq(2021,1)); % Struct with vector values across multiple dates S.inflation = [0.02; 0.02; 0.03; 0.03]; S.output = [1.0; 1.1; 1.2; 1.3]; sp = append(sp, S, rq(2021,1):rq(2021,4)); % Algebraic constraint enforced by shock EC sp = append(sp, {'Inflation{t} + Output = 0', 'EC'}, rq(2021,1), NaN); .. seealso:: simplan, export, query, initval, endval, histval .. index:: simplan.details .. _simplan.details: details -------- `details` - Display the raw property structure of a simplan object. Syntax: details(obj) Description: Displays the full internal property listing of the simplan object using MATLAB's built-in display, bypassing the overloaded `disp`. Useful for debugging or inspecting internal state such as ConditionMatrix, DynamicConstraints, initval_, endval_, and histval_ directly. Notes: - Equivalent to calling `builtin('disp', obj)`. - For a human-readable summary, use `disp` instead. - For querying specific variable values, use `query`. Example: details(sp) % shows raw property dump disp(sp) % shows formatted summary .. seealso:: disp, query, simplan .. index:: simplan.disp .. _simplan.disp: disp ----- `disp` - Display a readable summary of a simplan object. Syntax: disp(obj) Description: Prints a structured, human-readable summary of the simplan object to the console. The summary includes: - Simulation horizon (start and end dates, number of periods) - Initial regime - Status of initval, endval, and histval blocks (if set) - All conditioned endogenous variables with their non-NaN date-value pairs, grouped by variable - All conditioned exogenous variables with their non-NaN date-value pairs, grouped by variable and anticipation page - Dynamic (algebraic) constraints with their associated shocks, dates, and pages Only non-NaN entries are shown. Variables with no conditioning (all NaN) are omitted. Called automatically by MATLAB when `disp(obj)` is invoked, or indirectly via `display` when an expression is evaluated without a semicolon. Notes: - To see the raw property structure, use `details(obj)`. - To query specific variables interactively, use `query`. .. seealso:: details, query, simplan .. index:: simplan.endval .. _simplan.endval: endval ------- endval : Overloads/emulates Dynare's endval for the simplan class Syntax: obj = endval(obj, steady, C) Description: The `endval` method overloads/emulates Dynare's endval for the :ref:`simplan ` class. It sets initial conditions for simulation periods, considering the presence of steady state calculations and historical values. Input: - obj: The simplan object. - steady: A logical flag indicating whether steady state calculations should be performed. If true, the provided initial conditions (C) will be used to calculate the steady state, resulting in an updated C. - C: Initial conditions, start values and terminal conditions. For the syntax, see the help for initval. - In the absence of any other block, (the possibly updated) C provides initial conditions, terminal conditions and start values for perfect-foresight optimization. - In the presence of an initval block and/or a histval block, (the possibly updated) C provides terminal conditions and start values for perfect-foresight optimization. Output: - obj: Updated simplan object with initialized conditions. Example: sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions); Notes: - The `endval` method dominates `initval` in that it overrides the terminal conditions and the initial values for perfect-foresight optimization .. seealso:: - simplan .. index:: simplan.export .. _simplan.export: export ------- `export` - Compile conditioning information for simulation. Syntax:: [histdb, np] = export(obj, dsgemodel) [histdb, np, ss] = export(obj, dsgemodel) [histdb, np, ss, partitions] = export(obj, dsgemodel) Description: Compiles the conditioning information stored in a simplan object into outputs suitable for perfect-foresight simulation or conditional forecasting in RISE. The compilation resolves the following in order: 1. initval block (if set) — provides initial conditions and, in the absence of endval, terminal conditions and start values. 2. endval block (if set) — overrides terminal conditions and start values from initval. 3. histval block (if set) — overrides initial conditions from both initval and endval. 4. Explicit restrictions added via `append`. If steady=true was passed to initval or endval, the steady state is recomputed subject to the provided values before compilation. Inputs:: - obj : simplan object containing all conditioning information. - dsgemodel : RISE DSGE model object. Required when initval or endval was called with steady=true, in which case `export` calls `sstate` to recompute the steady state. For steady=false workflows, dsgemodel is still required but sstate is not called. Outputs:: - histdb : ts (time series) object covering [start_date, end_date]. Contains the compiled conditioning values for all endogenous and exogenous variables. NaN entries indicate unconstrained variable-date combinations. - np : Number of simulation periods. Equal to simul_periods, i.e. numel(start_date:end_date) - 1. - ss : Struct of start values for endogenous variables, or [] if neither initval nor endval was set. Fields are variable names; values are the corresponding start values used to initialize the perfect-foresight solver. Exogenous variables are excluded from ss. - partitions : Struct describing the layout of histdb and the extent of conditioning. Fields: .endogenous : column indices of endogenous variables in ConditionMatrix. .exogenous : column indices of exogenous variables in ConditionMatrix. .regime : column index of the regime variable. .constrained_periods : struct with fields: .endogenous : vector (n_periods x 1); entry k is the number of pages on which at least one endogenous variable is constrained at period k. .exogenous : same for exogenous variables. .regime : same for the regime variable. Notes: - `export` does not modify the simplan object. - The order of precedence for overlapping conditions is: histval > endval > initval > append. - Dynamic (algebraic) constraints stored in DynamicConstraints are not included in histdb — they are handled separately by the solver. Examples:: % Basic export [histdb, np] = export(sp, m); % Full output [histdb, np, ss, partitions] = export(sp, m); % Check how many periods have endogenous constraints [~,~,~,p] = export(sp, m); disp(p.constrained_periods.endogenous) .. seealso:: simplan, append, initval, endval, histval .. index:: simplan.histval .. _simplan.histval: histval -------- histval : Overloads/emulates Dynare's histval for the simplan class Syntax: obj = histval(obj, C) Description: The `histval` method overloads/emulates Dynare's histval for the :ref:`simplan ` class. It sets the historical values (initial conditions) for the perfect-foresight simulations. Input: - obj: The simplan object. - C: historical values to be set. The syntax is as follows:: Example 1: C = { 'y(0)', 1 'k(-1)', 12 'm{0}', 0.5 'x{-1}', 1 }; Example 2: C = { 'y(0)=1;' 'k(t-1)=12;' 'm{0}=0.5;' 'x{t-1}=1;' }; Example 3: C = 'y(0)=1; k(-1)=12; m{0}=0.5; x{-1}=1;'; Output: - obj: Updated simplan object with initialized conditions. Example: sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions); Notes: - The `histval` method dominates both `initval` and `endval` .. seealso:: - simplan .. index:: simplan.initval .. _simplan.initval: initval -------- initval : Overloads/emulates Dynare's initval for the simplan class Syntax: obj = initval(obj, steady, C) Description: The `initval` method overloads/emulates Dynare's initval for the :ref:`simplan ` class. It sets initial conditions for simulation periods, considering the presence of steady state calculations and historical values. Input: - obj: The simplan object. - steady: A logical flag indicating whether steady state calculations should be performed. If true, the provided initial conditions (C) will be used to calculate the steady state, resulting in an updated C. - C: Initial conditions, start values and terminal conditions. It can be provided as a cell array with variable-value pairs, or as a cell array with expressions for each variable:: Example 1: C = { 'y', 1 'k', 12 'm', 0.5 'x', 1 }; Example 2: C = { 'y=1;' 'k=12;' 'm=0.5;' 'x=1;' }; Example 3: C = 'y=1; k=12; m=0.5; x=1;'; - In the absence of any other block, (the possibly updated) C provides Initial conditions, terminal conditions and start values for perfect-foresight optimization. - In the presence of a histval block, (the possibly updated) C provides, terminal conditions and start values for perfect-foresight optimization. - In the presence of a endval block, (the possibly updated) C provides only initial conditions. Output: - obj: Updated simplan object with initialized conditions. Example: sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions); Notes: - The `initval` method cannot be called twice. .. seealso:: - simplan .. index:: simplan.query .. _simplan.query: query ------ `query` - Query conditioning values from a simplan object. Syntax: [values, dates, pages] = query(obj, vname) [values, dates, pages] = query(obj, vname, target_dates) [values, dates, pages] = query(obj, vname, target_dates, target_pages) Description: Retrieves conditioning values stored in a simplan object for a given variable, optionally filtered by date and anticipation page. Only non-NaN entries are returned. Results are also printed to the console in a formatted table. Anticipation pages: page 1 = shock is unanticipated (hits at the specified date) page k = shock is known k-1 periods ahead of the specified date Inputs: - obj : simplan object. - vname : Name of the variable to query. Must be in variable_list (endogenous, exogenous, or 'regime'). - target_dates : (Optional) Date or vector of dates to query. Must be within [start_date, end_date] and of the same type as the simplan horizon. Defaults to all dates in the simulation horizon. - target_pages : (Optional) Scalar or vector of anticipation pages to query. Must be positive integers within [1, shock_horizon+1]. Defaults to all pages. Outputs: - values : Numeric matrix of size (n_active_dates x n_active_pages). Contains only rows and columns with at least one non-NaN entry. NaN entries within the retained rows/columns are shown as '---' in the printed table. - dates : Vector of dates corresponding to rows of values. Same type as simplan horizon (numeric or RISE date). - pages : Vector of page indices corresponding to columns of values. If no conditioned values are found, all outputs are empty ([]) and a warning ('simplan:query') is issued. Notes: - `query` prints a formatted table to the console on every call. The printed output cannot be suppressed — capture outputs and redirect if console output is unwanted. - `query` does not distinguish between values set explicitly via `append` and values set implicitly by steady-state initialization. To inspect only explicitly set values, use `append` selectively and query the specific dates of interest. Examples: % Query all conditioned dates for inflation [v, d, p] = query(sp, 'inflation'); % Query inflation at specific dates [v, d, p] = query(sp, 'inflation', rq(2021,1):rq(2021,4)); % Query shock ea at anticipation page 2 (known 1 period ahead) [v, d, p] = query(sp, 'ea', rq(2022,1), 2); % Query across multiple pages [v, d, p] = query(sp, 'ea', [], 1:3); .. seealso:: simplan, append, disp .. index:: simplan.simplan .. _simplan.simplan: simplan -------- :ref:`simplan ` - Simulation and forecasting plan for DSGE models. Syntax: obj = simplan(m, horizon, initialRegime) obj = simplan(m, horizon, initialRegime, 'shockInit', spec) obj = simplan(m, horizon, initialRegime, 'shockInit', spec, C) obj = simplan(m, horizon, initialRegime, C) Description: Creates a simulation/forecasting plan for a DSGE model. The plan stores conditioning information — fixed values for endogenous and exogenous variables at specific dates and anticipation horizons — that is later compiled by `export` for use in perfect-foresight simulation or conditional forecasting. If the model has not been solved, :ref:`simplan ` solves it automatically before constructing the plan. Inputs: - m : RISE DSGE model object. Solved or unsolved — if unsolved, :ref:`simplan ` calls `solve` internally. - horizon : 1x2 vector [start_date, end_date] defining the simulation horizon. start_date is the last date of history; end_date is the last date of simulation. Must satisfy start_date < end_date. - initialRegime : Positive integer selecting the initial regime for regime-switching models. For single-regime models, pass 1 or []. Required for multi-regime models. Optional Name-Value Inputs: - 'shockInit' : Controls how exogenous variables are initialized in the ConditionMatrix. Accepted values: [] Legacy behavior — shocks initialized to their steady-state values. This is the default when 'shockInit' is not provided. 'zero' All shocks set to zero across all periods and anticipation pages. 'randn' All shocks drawn independently from N(0,1). Reproducibility is the caller's responsibility via `rng`. scalar All shocks set to the given numeric value, e.g. 'shockInit', 0.01. struct Per-shock control. Each field name must match a variable in exo_list. Field values can be 'zero', 'randn', or a numeric scalar. Shocks not mentioned default to zero. Example: spec = struct('ea','randn','eb',0); Optional Positional Inputs: - C : Initial conditioning information passed directly to `append`. Accepts all formats supported by `append`: 3- or 4-column cell array, or triplet (vname, date, value). See `append` for details. Outputs: - obj : Initialized simplan object. Notes: - The ConditionMatrix is a 3D array of size: (n_periods) x (n_endo + n_exo + 1) x (shock_horizon + 1) where the third dimension corresponds to anticipation pages: page 1 = unanticipated shock (hits at date) page k = shock known k-1 periods ahead - Endogenous variables are initialized to their steady-state values. - The regime column is initialized to 1 for single-regime models. - For multi-regime models, the regime column is left as NaN until set explicitly via `append`. Examples: % Basic plan with numeric dates sp = simplan(m, [1, 40], 1); % Plan with RISE dates sp = simplan(m, [rq(1990,1), rq(2000,4)], 1); % Initialize all shocks from N(0,1) rng(42) sp = simplan(m, [1, 40], 1, 'shockInit', 'randn'); % Per-shock initialization spec = struct('ea', 'randn', 'eb', 0); sp = simplan(m, [1, 40], 1, 'shockInit', spec); % Initialize with immediate conditioning sp = simplan(m, [1, 40], 1, 'y', 5, 1.5); .. seealso:: append, export, initval, endval, histval, query